home *** CD-ROM | disk | FTP | other *** search
-
-
-
- Tk_GetBitmap(3) Tk Library Procedures
-
-
-
- _________________________________________________________________
-
- NAME
- Tk_GetBitmap, Tk_DefineBitmap, Tk_NameOfBitmap,
- Tk_SizeOfBitmap, Tk_FreeBitmap, Tk_GetBitmapFromData - main-
- tain database of single-plane pixmaps
-
- SYNOPSIS
- #include <tk.h>
-
- Pixmap
- Tk_GetBitmap(_i_n_t_e_r_p, _t_k_w_i_n, _i_d)
-
- int |
- Tk_DefineBitmap(_i_n_t_e_r_p, _n_a_m_e_I_d, _s_o_u_r_c_e, _w_i_d_t_h, _h_e_i_g_h_t) |
-
- Tk_Uid
- Tk_NameOfBitmap(_d_i_s_p_l_a_y, _b_i_t_m_a_p) |
-
- Tk_SizeOfBitmap(_d_i_s_p_l_a_y, _b_i_t_m_a_p, _w_i_d_t_h_P_t_r, _h_e_i_g_h_t_P_t_r) |
-
- Tk_FreeBitmap(_d_i_s_p_l_a_y, _b_i_t_m_a_p) |
-
- ARGUMENTS
- Tcl_Interp *_i_n_t_e_r_p (in) Interpreter to use for
- error reporting.
-
- Tk_Window _t_k_w_i_n (in) Token for window in
- which the bitmap will
- be used.
-
- Tk_Uid _i_d (in) Description of bitmap;
- see below for possible
- values.
-
- Tk_Uid *_n_a_m_e_I_d (in) Name for new bitmap to
- be defined.
-
- char *_s_o_u_r_c_e (in) Data for bitmap, in
- standard bitmap for-
- mat. Must be stored
- in static memory whose
- value will never
- change.
-
- unsigned int _w_i_d_t_h (in) Width of bitmap.
-
- unsigned int _h_e_i_g_h_t (in) Height of bitmap.
-
- unsigned int *_w_i_d_t_h_P_t_r (out) Pointer to word to
- fill in with _b_i_t_m_a_p's
- width.
-
-
-
- Tk 1
-
-
-
-
-
-
- Tk_GetBitmap(3) Tk Library Procedures
-
-
-
- unsigned int *_h_e_i_g_h_t_P_t_r (out) Pointer to word to
- fill in with _b_i_t_m_a_p's
- height.
-
- Display *_d_i_s_p_l_a_y (in) Display for which _b_i_t_-
- _m_a_p was allocated. |
-
- Pixmap _b_i_t_m_a_p (in) Identifier for a bit-
- map allocated by
- Tk_GetBitmap.
- _________________________________________________________________
-
-
- DESCRIPTION
- These procedures manage a collection of bitmaps (one-plane
- pixmaps) being used by an application. The procedures allow
- bitmaps to be re-used efficiently, thereby avoiding server
- overhead, and also allow bitmaps to be named with character
- strings.
-
- Tk_GetBitmap takes as argument a Tk_Uid describing a bitmap.
- It returns a Pixmap identifier for a bitmap corresponding to
- the description. It re-uses an existing bitmap, if possi-
- ble, and creates a new one otherwise. At present, _i_d must
- have one of the following forms:
-
- @_f_i_l_e_N_a_m_e _F_i_l_e_N_a_m_e must be the name of a file con-
- taining a bitmap description in the
- standard X11 or X10 format.
-
- _n_a_m_e _N_a_m_e must be the name of a bitmap
- defined previously with a call to
- Tk_DefineBitmap. The following names
- are pre-defined by Tk:
-
- error The international "don't" |
- symbol: a circle with a |
- diagonal line across it.
-
- gray50 50% gray: a checkerboard
- pattern where every other
- bit is on.
-
- gray25 25% gray: a pattern where
- 25% of the bits are on, con-
- sisting of all the bit posi-
- tions that can be reached by
- a chess knight starting at
- (0,0).
-
- hourglass An hourglass symbol. |
-
-
-
-
- Tk 2
-
-
-
-
-
-
- Tk_GetBitmap(3) Tk Library Procedures
-
-
-
- info ||
- A large letter ``i''. |
-
- quest- |
- head ||
- The silhouette of a human |
- head, with a question mark |
- in it. |
-
- ques- |
- tion ||
- A large question-mark. |
-
- warn- |
- ing ||
- A large exclamation point.
-
-
- Under normal conditions, Tk_GetBitmap returns an identifier
- for the requested bitmap. If an error occurs in creating
- the bitmap, such as when _i_d refers to a non-existent file,
- then None is returned and an error message is left in
- _i_n_t_e_r_p->_r_e_s_u_l_t.
-
- Tk_DefineBitmap associates a name with in-memory bitmap data |
- so that the name can be used in later calls to Tk_GetBitmap. |
- The _n_a_m_e_I_d argument gives a name for the bitmap; it must |
- not previously have been used in a call to Tk_DefineBitmap. |
- The arguments _s_o_u_r_c_e, _w_i_d_t_h, and _h_e_i_g_h_t describe the bitmap. |
- Tk_DefineBitmap normally returns TCL_OK; if an error occurs |
- (e.g. a bitmap named _n_a_m_e_I_d has already been defined) then |
- TCL_ERROR is returned and an error message is left in |
- _i_n_t_e_r_p->_r_e_s_u_l_t. Note: Tk_DefineBitmap expects the memory |
- pointed to by _s_o_u_r_c_e to be static: Tk_DefineBitmap doesn't |
- make a private copy of this memory, but uses the bytes |
- pointed to by _s_o_u_r_c_e later in calls to Tk_GetBitmap.
-
- Typically Tk_DefineBitmap is used by #include-ing a bitmap
- file directly into a C program and then referencing the
- variables defined by the file. For example, suppose there
- exists a file stip.bitmap, which was created by the bitmap
- program and contains a stipple pattern. The following code
- uses Tk_DefineBitmap to define a new bitmap named foo:
- Pixmap bitmap;
- #include "stip.bitmap"
- Tk_DefineBitmap(interp, Tk_GetUid("foo"), stip_bits,
- stip_width, stip_height);
- ...
- bitmap = Tk_GetBitmap(interp, tkwin, Tk_GetUid("foo"));
- This code causes the bitmap file to be read at compile-time
- and incorporates the bitmap information into the program's
- executable image. The same bitmap file could be read at
-
-
-
- Tk 3
-
-
-
-
-
-
- Tk_GetBitmap(3) Tk Library Procedures
-
-
-
- run-time using Tk_GetBitmap:
- Pixmap bitmap;
- bitmap = Tk_GetBitmap(interp, tkwin, Tk_GetUid("@stip.bitmap"));
- The second form is a bit more flexible (the file could be
- modified after the program has been compiled, or a different
- string could be provided to read a different file), but it
- is a little slower and requires the bitmap file to exist
- separately from the program.
-
- Tk_GetBitmap maintains a database of all the bitmaps that
- have been created. Whenever possible, it will return an
- existing bitmap rather than creating a new one. This
- approach can substantially reduce server overhead, so
- Tk_GetBitmap should generally be used in preference to Xlib
- procedures like XReadBitmapFile.
-
- The bitmaps returned by Tk_GetBitmap are shared, so callers
- should never modify them. If a bitmap must be modified
- dynamically, then it should be created by calling Xlib pro-
- cedures such as XReadBitmapFile or XCreatePixmap directly.
-
- The procedure Tk_NameOfBitmap is roughly the inverse of
- Tk_GetBitmap. Given an X Pixmap argument, it returns the _i_d
- that was passed to Tk_GetBitmap when the bitmap was created. |
- _B_i_t_m_a_p must have been the return value from a previous call |
- to Tk_GetBitmap.
-
- Tk_SizeOfBitmap returns the dimensions of its _b_i_t_m_a_p argu- |
- ment in the words pointed to by the _w_i_d_t_h_P_t_r and _h_e_i_g_h_t_P_t_r |
- arguments. As with Tk_NameOfBitmap, _b_i_t_m_a_p must have been |
- created by Tk_GetBitmap.
-
- When a bitmap returned by Tk_GetBitmap is no longer needed,
- Tk_FreeBitmap should be called to release it. There should
- be exactly one call to Tk_FreeBitmap for each call to
- Tk_GetBitmap. When a bitmap is no longer in use anywhere
- (i.e. it has been freed as many times as it has been gotten)
- Tk_FreeBitmap will release it to the X server and delete it
- from the database.
-
-
- BUGS
- In determining whether an existing bitmap can be used to
- satisfy a new request, Tk_GetBitmap considers only the
- immediate value of its _i_d argument. For example, when a
- file name is passed to Tk_GetBitmap, Tk_GetBitmap will
- assume it is safe to re-use an existing bitmap created from
- the same file name: it will not check to see whether the
- file itself has changed, or whether the current directory
- has changed, thereby causing the name to refer to a dif-
- ferent file.
-
-
-
-
- Tk 4
-
-
-
-
-
-
- Tk_GetBitmap(3) Tk Library Procedures
-
-
-
- KEYWORDS
- bitmap, pixmap
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- Tk 5
-
-
-
-
